Certification Guide
100% Pure Java Certification is an award bestowed upon Java programs that meet the criteria set forth in this guide. Certified programs have the right to display the 100% Pure Java logo on their software package. The logo assures customers that your program relies only on the documented and specified Java platform, so that it will run on any Java-compatible computer. The end result is that your program delivers on the promise of "Write Once, Run Anywhere."
Certification is a process by which you inspect your Java program for compliance to the standards in this guide using the procedures and test tools provided by Sun. Once your program meets the specified criteria, you submit your program along with the required documentation to an independent Certification Center for inspection and approval.
This guide will assist you in the process of obtaining 100% Pure Java Certification for your Java program by providing you with all the necessary information to complete the process. The steps described in this guide are necessary to ensure that your Java program is 100% Pure Java and that it will meet your customer's expectations of a 100% Pure Java certified product.
If you are gathering information about 100% Pure Java Certification, this document, the 100% Pure Java Cookbook, and the static tool, JavaPureCheck, are all freely available on the Web and may be obtained prior to registration from http://www.suntest.com/100percent/.
The 100% Pure Java Certification process begins by registering your program for certification and ends when you receive a certification report from the Certification Center. The certification process is divided into two sets of tasks:
Completion of the assurance process enables the Certification Center to complete the verification process accurately and efficiently, and issue a certification report. The following is an overview of the assurance process and the verification process that the Certification Center will perform.
Register for the 100% Pure Java Certification process. After registering, you will be able to download the 100% Pure Java Certification package. This certification package contains all the tools and documentation necessary for you to perform the assurance process and create the verification package for submission to KeyLabs.
The certification fee is applied towards the cost of testing services provided by KeyLabs and the tools support services provided by SunTest. For details on the certification fee, see http://www.keylabs.com/100percent/.
The certification tests begin with a static purity test of your Java program to ensure that it has been written to the definition of 100% Pure Java as described in the 100% Pure Java Cookbook.
The static purity test is performed by JavaPureCheck, which is a tool included in the Certification package. If the results of the static check indicates that your Java program is impure, or possibly impure, you will need to submit explanations for the problems found by JavaPureCheck.
To ensure your Java program is pure, you will need to submit an exerciser that demonstrates that your Java program doesn't depend on the idiosyncrasies of a particular operating system or browser. The exerciser has two components: (1) creating an automated or manual exerciser; and (2) measuring method coverage.
Creating an Automated or Manual Exerciser
For executing the exerciser, you will need to create an automated exerciser. The exerciser must be written in Java. The certification package includes JavaSpin, which is a tool you can use to create an automated test of your GUI or AWT-based Java program.
If it is impossible to create an automated exerciser for your program, you may also submit an exerciser in the form of a script of instructions for manual testing.
Measuring Method Coverage
Method coverage is a measure of how many of the program's methods are executed by a test. To gather coverage information on your program, you first use the JDK java compiler to create instrumented class files that can be used to gather coverage information. When the instrumented classes are executed, coverage information is accumulated into a coverage file. A coverage reporting tool, jcrpt, is included in the certification package; it generates a coverage report that shows which methods in your program have been executed during testing. The tests you submit as part of the verification package must achieve a specific level of method coverage, detailed later in this guide, in order to demonstrate portable execution.
After completing the assurance process, you will bundle your Java program and results into a verification package and submit it to the Certification Center for verification.
The verification process is performed by the Certification Center. Their goal is to help you certify your Java program as 100% Pure Java, while ensuring the 100% Pure Java standards are met. In essence, they will re-run the tests you performed to ensure that there are no discrepancies.
Upon arrival, the submitted verification package is evaluated to determine its completeness. Incomplete or nonconforming verification packages will be rejected. Rejected verification packages can be resubmitted in accordance with the procedure defined in the Resubmission Procedure section.
After establishing the completeness of your verification package, the Certification Center will run the static check on your submitted Java class files using JavaPureCheck. These results will then be compared with your annotated results. If any warning or error does not have an attached explanation, the verification package will be rejected.
Following the completion of the static check, the Certification Center will set-up and install your Java program on the reference Java platforms according to the instructions you provide. The reference platforms are listed in Appendix 1 - Reference Java Platforms. If your Java program cannot be installed on the reference Java platforms, the verification package will be rejected.
The certification fee allows for 1/2 hour of setup and installation time per reference Java platform. If the verification package contains complex set-up procedures or requirements, an additional set-up fee may be required. If you have special requirements, please inform KeyLabs as early as possible so they may prepare for your verification cycle.
KeyLabs will execute the automated or manual script you created during the assurance process on the reference Java platforms. The script must run to completion on each platform. Following the execution of the test scripts, KeyLabs will evaluate whether or not the execution met the method coverage criteria outlined later in this document.
If there are no discrepancies and all criteria have been met, you will receive a certification report that reads "accepted." If any discrepancies have been found by the Certification Center, you will receive a report that reads "rejected," and details the discrepancies found. You can check the status of your verification package on the Internet at http://www.keylabs.com/100percent.
The principle behind the 100% Pure Java Certification process is for you to perform the assurance tasks at your site on your Java code before submitting the results to KeyLabs, the Certification Center. By performing these tasks you should know beforehand whether your Java program is eligible to receive 100% Pure Java Certification; thus, saving time and money by reducing the chances of having to resubmit your program.
In this section, each task in the assurance process is described and broken down into discrete subtasks. Exit criteria are listed at the end of each task. The exit criteria are a distillation of what you should have accomplished before proceeding to the next step. Use the table in Appendix 2 - Exit Criteria Checklist to ensure you have completed each required task.
 |
Notes:
|
Begin the certification process by registering your product for 100% Pure Java Certification.
The 100% Pure Java registration form can be accessed on the Web at http://www.keylabs.com/100percent/register.htm.
Complete the form with your company, contact, product, and billing information.
Under product information you must designate what type of Java program you intend to certify. A Java program may currently be certified as an applet, an application, or a class library. You must select only one.
Follow the instructions to submit the form. Once approved, the submission contact you designate will receive a user ID and password by e-mail that will allow you to download the 100% Pure Java Certification package.
The 100% Pure Java Certification package contains all the documentation and tools you will need to perform the 100% Pure Java assurance process. Once you have received your user ID and password, access the SunTest Web site at http://www.suntest.com/100percent/.
You can use your user ID and password to download the 100% Pure Java Certification package, which is named cpd. It is available in various archive formats, including the Java archive format (JAR). Unpack the certification package file bundle. The contents of the certification package directory are described in Appendix 3 - Certification Package Contents.
Read through this document and the documents mentioned below:
Be sure you understand the tools provided in the package (JavaPureCheck, jcrpt, and JavaSpin) and the steps involved in the assurance process.
100%
Pure Java Certification registration is approved.
The
100% Pure Java Certification package is downloaded.
The
100% Pure Java Certification documents and sample verification package
have been reviewed.
The verification package is the archive file you will submit to KeyLabs for 100% Pure Java Certification. The package will contain your Java program and the results of the assurance process you have performed. The contents of the package you submit must conform to the verification package description defined in Appendix 4 - Verification Package Contents.
The 100% Pure Java Certification package contains a completed verification package for a sample Java program in directory CPDIR/example.Inspect this sample for the steps involved in creating a verification package.
In addition, a template directory is provided in CPDIR/template. This directory contains the proper format for a submitted verification package. Use this directory as a template for creating the structure of your verification package directory by placing its contents into the directory VPDIR.
Ensure that the final version of your Java class files are placed in the directory VPDIR/classes. If you create any subdirectories, the names of the subdirectories must be included in the file VPDIR/classes/manifest.txt.
To run JavaPureCheck you must have the latest JDK release installed on your system. However, you are not required to compile your program with the latest JDK release. JavaPureCheck can be run on class files compiled with any version of the JDK. You can download the latest version of the JDK from http://java.sun.com/products/JDK/index.html.
The
verification package directory is created according to the template directory
CPDIR/template.
The
VPDIR/classes directory contains all the classes for your Java program.
The
file VPDIR/classes/manifest.txt is filled out with the names of all the
subdirectories containing Java class files.
The
latest version of JDK is installed on the system where you will run JavaPureCheck.
The static purity check of your Java program is performed by JavaPureCheck, which is a tool developed by SunTest. JavaPureCheck can be used at any point during the development cycle. Using it early and often will help you ensure your program is 100% Pure Java and will prevent costly revisions to the code during the assurance process.
The instructions are located in CPDIR/doc/tools/index.html.
Invoke the GUI or command-line version of JavaPureCheck on the class files of your Java program:
java JavaPureCheckor
java JavaPureCheck -d model VPDIR/classes
where model is jdk102 or jdk11
These are the class files that you copied to VPDIR/classes. Ensure that the class files are in the final form you will submit to the Certification Center. JavaPureCheck will scan for the Java portability pitfalls as described in the 100% Pure Java Cookbook and Appendix 5 - Explanations for Purity Problems.
JavaPureCheck displays the names of the Java classes that have indicated warnings and errors. You must attach an explanation for all warnings and errors indicating why the nonconformance is valid or portable in this particular instance. Only official JavaSoft Variances (cited by variance number) are allowed for reported errors. See Appendix 5 - Explanations for Purity Problems or the 100% Pure Java Cookbook for details. Add the explanations by using the explanation input feature of the GUI, or manually edit the results file if using the command-line mode.
If the results from the JavaPureCheck program indicates that your Java program is 100% Pure Java, you do not need to supply any explanations.
Copy the JavaPureCheck results file (default is results.jpc) to file VPDIR/results/results.jpc. If you attached warning or error explanations, the GUI version of JavaPureCheck will store your explanations in file resultsEXP.ser in the current directory where you ran JavaPureCheck. Copy the explanations file to file VPDIR/results/resultsEXP.ser.
JavaPureCheck
has been run on the final version of your Java class files.
The
results file from JavaPureCheck is placed in file VPDIR/results/results.jpc.
All
errors and warnings reported by JavaPureCheck have attached explanations.
The
JavaPureCheck explanations file, if required, is placed in file VPDIR/results/resultsEXP.ser.
The purpose of the exerciser is to ensure that the possibly impure parts of your program, as flagged by JavaPureCheck, are truly pure. This is accomplished by exercising your program on two different Java Compatible` platforms (see Appendix 1 - Reference Java Platforms.)
The steps of the exerciser differ depending on whether or not your Java program can execute in a JDK 1.1 environment. Even if your program was developed using JDK 1.0.2, it may run just fine in a JDK 1.1 environment. If your program can execute in a JDK 1.1 environment, perform the steps for JDK 1.1 Compatible Java Programs.
If your program runs in a JDK 1.1 environment but does not compile in this environment, you will be able to use the capture/replay tool, JavaSpin; however, you will not be able to use the coverage tool, jcrpt. You must be able to recompile under JDK 1.1 to get coverage information. If your program does not compile under JDK 1.1, perform the steps for JDK 1.0 Only Java Programs.
The steps below are for Java programs that are developed for, or can compile under a JDK 1.1 environment.
The driver, or exerciser, is used to automatically execute your program. You can either create your own, or use JavaSpin, which is included in the certification package. JavaSpin will record an interactive session of your Java GUI program or applet.
If your Java program doesn't use a GUI interface, you must supply your own driver program. In any case, the driver program you create must be written in Java and must indicate whether the exerciser successfully ran to completion.
If the creation of an automatic driver is impossible, you can also submit instructions for manual testing. This is discouraged, as manual exercising is less repeatable and more labor-intensive than automated exercise.
Note that you can use any combination of drivers you choose: JavaSpin drivers, other Java driver programs, and (if necessary) manual instructions.
If you chose to create your own driver program, you must put the Java sources of your driver in directory VPDIR/autorun.After creating your driver, proceed to Step 4.1.d.
If you choose to use JavaSpin, proceed to Step 4.1.b.
The instructions are found at CPDIR/doc/tools/javaspin.html.
Run JavaSpin on your class files in VPDIR/classes. Place all your generated JavaSpin scripts in directory VPDIR/autorun. JavaSpin script filenames must be named with the following naming convention: jstest1, jstest2, jstest3, etc. In file VPDIR/howto.txt (described in Step 5.a) under the section Auto Run, include the names of the created JavaSpin scripts, the class filename to run, and any arguments to use with JavaSpin playback execution.
To ensure the automated execution of your Java program exercises your program sufficiently, you must use your Java source files to create instrumented class files that gather and report method coverage information. The JDK 1.1 Java compiler must be used to create the instrumented class files of your Java program. Refer to the JCRPT instructions (CPDIR/doc/tools/jcrpt.html) for details on how to create coverage instrumented class files and the coverage database file.
The instrumented class files must be placed in directory VPDIR/inst_classes, and the coverage database file must be placed in file VPDIR/inst_classes/mcov/coverage.jcv.
Applets and applications must achieve the following coverage criteria:
| |
Note: Class libraries that you intend to license to third-parties under the 100% Pure Java logo must achieve 100% method coverage. Libraries face these extended coverage criteria because of the need to ensure that any Java program that uses the library will remain 100% Pure Java. |
In some programs it may be impossible or extremely impractical to achieve 100% method coverage of certain libraries or classes. Don't Panic! If you are in this situation, you will need to annotate the coverage report produced by jcrpt with individual explanations for each method that is not executed by the test. The explanations must indicate why it is not possible to execute the method in a normal operating environment and also why the method does not pose a portability risk. Save the annotated coverage report to file VPDIR/results/results.cov.
The steps below are for Java programs that are developed for, or run only under, the JDK 1.0 environment.
If your JDK 1.0-based Java program uses AWT and does not run in a JDK 1.1 environment, you will need to provide manual instructions on how to sufficiently exercise the indicated portability problem areas in your code. Put these instructions in file VPDIR/howto.txt (described in Step 5.a) under the heading Manual Run.
KeyLabs will assess the functional coverage of the Manual Run instructions and their adequacy in exercising the possibly impure areas in your code. If they determine that the instructions do not achieve these objectives, your submission could be rejected.
You may supply an automated exerciser created by means other than JavaSpin, if your Java program is JDK 1.0 only. However, you will not be able to instrument your program for coverage. The Certification Center will assess the adequacy of your supplied exerciser.
All
JavaSpin script files and Java driver sources are located in directory
VPDIR/autorun and the required instructions appear in file VPDIR/howto.txt
under the heading Auto Run.
The
coverage instrumented class files created by JCRPT are located in directory
VPDIR/inst_classes.
The
coverage database file is named VPDIR/inst_classes/mcov/coverage.jcv.
The
automatic execution of your Java program has achieved the required method
coverage criteria outlined in Step 4.1.e.
The
coverage report file including explanations for non-executed methods is
named VPDIR/results/results.cov.
Manual
testing instructions are included in file VPDIR/howto.txt under
the heading Manual Run
If an
automated exerciser is supplied, the Java sources of the automated driver
are located in directory VPDIR/autorun.
All the hard work is now complete and you are ready to submit the results of the assurance process to the Certification Center. Ensure you have completed all previous tasks and each of the exit criteria have been met.
Create a text file with the following sections: Setup, Install, Install Check, Auto Run, and Manual Run. The file must be named howto.txt and be located in directory VPDIR. Fill in the appropriate information for each section as described below.
Verify that your verification package directory conforms exactly to the directory structure and content as described in Appendix 4 - Verification Package Contents. Anything missing, mislabeled, or extraneous may cause a certification rejection and you will need to resubmit. Check twice and ship once! After ensuring that everything is in order, create a ZIP, TAR or JAR file of your verification package directory and name it:
<company-name>_<user-initials>.zip or .tar or .jar
The
VPDIR/howto.txt file is created with the sections Setup, Install,
Install Check, Auto Run, and Manual Run, and includes detailed instructions
for those sections.
The
verification package has been verified in accordance to the verification
package directory contents as specified in Appendix
4 - Verification Package Contents.
The
verification package directory has been compressed into a ZIP, TAR or JAR-formatted
file with the name
company-name_user-initials.zip or .tar or .jar
The Certification Center, KeyLabs, must be notified that you are ready to submit the verification package. You must fill out the verification request form, which can be accessed on the Web at http://www.keylabs.com/100percent/. Once this form is filled out, you will be instructed where to upload your verification package archive. Instructions will be supplied by KeyLabs in the event you cannot upload the verification package electronically.
KeyLabs will be monitoring the progress of your verification package through their process. To check on your progress, go to http://www.keylabs.com/100percent/ and use your submission number and password to access your private progress report.
When the verification process is complete, KeyLabs will send a certification report via e-mail to the submission contact. This report will indicate whether the product has been "accepted" or "rejected." If the certification report indicates "rejected," you will be given the exact reasons for rejection. If your certification is rejected, you may resubmit your product as outlined in Resubmission Procedure. If the decision by KeyLabs is contested, you should follow the grievance resolution procedure outlined in section Grievance Procedure.
The
verification request form has been filled out and acknowledged by KeyLabs.
The
verification package archive has been uploaded to KeyLabs.
The
certification report has been received.
If you need to resubmit your verification package, please contact KeyLabs at (801) 377-5484 or 100percentpure@keylabs.com
Contact JavaSoft via e-mail at 100percentpure-program@javasoft.com.
Variance application is normally made through KeyLabs.
The dynamic platform test performed by KeyLabs requires that your exerciser run to completion on at least two unique Java platforms. A Java platform is a combination of the operating system and a Java Compatible implementation of the Java Virtual Machine. (Check the KeyLabs Web site at http://www.keylabs.com/100percent for the latest updates to the information in this section.)
| |
Note: Currently, all applications and libraries are required to pass the dynamic platform test on Win95/NT with Sun's JDK, and Solaris with Sun's JDK. As additional 1.1 Java Compatible platforms become available from other vendors they will also be made available for testing. |
In the case of applet certification, the implementation of the Java Virtual Machine is integrated into the Web browser where the applet runs. An applet will pass the dynamic test if the test driver runs to completion on two unique Java platforms (of your choice) with the following criteria: the operating systems are not the same, and the two browsers used are from different vendors. The purpose of this "distribution requirement" is to assure that your Java program does not depend on the idiosyncrasies of one operating system or one browser.
| |
Note: Currently, only the HotJava Browser is available for certification of 1.1 applets. As additional 1.1 Java Compatible browsers become available from other vendors they will also be made available for testing. |
| |
Note: If you are certifying a 1.0 applet you must choose two unique reference Java platforms from Table 2. |
The certification package contains the documentation, tools and forms necessary for 100% Pure Java Certification. The certification package is obtained from SunTest's Web site at http://www.suntest.com/100percent/. The package can only be downloaded after your registration for 100% Pure Java Certification has been approved and you have received a registration password from KeyLabs.
Table 4 lists the directories and files you will find in the certification package.
| |
Note: The certification package directory is named cpd. |
| DIRECTORY NAME | FILE NAME | CONTENTS |
|---|---|---|
| cpd | README.txt | Explains the content of each directory. |
| cpd | index.html | HTML reference to the documentation. |
| cpd/example | Contains a sample verification package. | |
| cpd/template | Contains the basic setup and explanation for the certification package that you will submit. Copy this directory, and use it to help guide you through the process. | |
| cpd/docs | Holds the documentation for the tools. | |
| cpd/tools | Contains all the tools and classes needed by the tools JavaSpin, JCRPT, and JavaPureCheck. |
The verification package is the file bundle you deliver to the Certification Center for 100% Pure Java Certification. It contains your Java program class files and the results of the assurance process you performed at your site.
Table 5 describes the directories and files you must deliver to the Certification Center for 100% Pure Java Certification.
| |
Note: The name of the sample verification package directory is template. |
| |
Note: For a detailed HTML-generated list of the purity problems,
you can run JavaPureCheck to generate a report: JavaPureCheck will create the HTML report <model>.html. |
Classes are categorized into one of three levels:
You must provide explanations for warnings and errors that describes why the reported problem does not in fact impede portability. Below is list of the problems reported by JavaPureCheck, with an indication of possible explanations: